@littlemissrobot/sass-functions

Little Miss Robot - Sass functions

This repository contains Sass (Dart Sass) based functions that we, at Little Miss Robot, like to use to make our wonderful lives in the world of SASS more wondeful. These functions are also mainly used throughout our other libraries to manage recurring tasks.

This package does not contain or generate any CSS. It simply provides a couple of @function statements for you to make use of.

IMPORTANT

This library makes use of Dart Sass, which is the primary implementation of Sass. Make sure that your Sass compiler is making use of Dart Sass.

This means that if you are using a task manager (like Gulp) or a module bundler (like Webpack), you must indicate which compiler it should use for compiling Sass to CSS.

Furthermore, this library makes heavy use of Sass modules: @use. Therefore we recommend importing and using this library with the @use statement.

Install

# As a dependency
$ npm install @littlemissrobot/sass-functions
# As a dev-dependency
$ npm install --save-dev @littlemissrobot/sass-functions

Usage

Through the main entry point

1. Import the library from the node_modules folder:

@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-functions" as _functions;

1. Functions are now available within the _functions namespace:

h1 {
    margin-bottom: _functions.px_rem(16px);
}

1. That's (mind-blowingly) it! The functions are seperated with internal namespaces, where functions related to a map are namespaced with _functions.map_[FUNCTION-NAME] or a list would be _functions.list_[FUNCTION-NAME].

Through the partial entry points

1. Import the partial of the library from the node_modules folder.

@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-functions/px" as _px;

1. Functions are now available within the _px namespace:

h1 {
    margin-bottom: _px.rem(16px);
}

1. That's (mind-blowingly) it! There are a number of partials to use the functions from:

   • "sass-functions/list" as _list;
   • "sass-functions/map" as _map;
   • "sass-functions/math" as _math;
   • "sass-functions/number" as _number;
   • "sass-functions/px" as _px;
   • "sass-functions/rem" as _rem;
   • "sass-functions/string" as _string;

Functions

List

These functions are namespace with list_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.list_includes($list, 5);

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/list" as _list;

_list.includes($list, 5);

includes($list, $item)

Checks if the list contains a certain item. Returns a boolean.

Parameters:

• $list: the list to search within
• $item: the item to search for in the list

@use "@littlemissrobot/sass-functions/list" as _list;

$list: (1, 2, 3, 4, 5);

_list.includes($list, 5); // true
_list.includes($list, 10); // false

is-low-to-high($list)

Checks if the numbers in the list are ordered lowest to highest.

Parameters:

• $list: the list which contains the numbers.

@use "@littlemissrobot/sass-functions/list" as _list;

$list1: (2, 1, 3);
$list2: (1, 2, 3);

_list.is-low-to-high($list1); // false
_list.is-low-to-high($list2); // true

merge-unique($lists...)

Merges multiple lists and removes any duplicates.

Parameters:

• $lists...: any amount of lists to merge together

@use "@littlemissrobot/sass-functions/list" as _list;

$list1: (1, 2, 3);
$list2: (1, 2, 3, 4, 5);
$list3: (4, 5, 6, 7, 8);

_list.merge-unique($list1, $list2, $list3); // (1, 2, 3, 4, 5, 6, 7, 8)

remove-duplicates($list)

Loops through the list and removes duplicate values.

Parameters:

• $list: the list to remove the duplicates from

@use "@littlemissrobot/sass-functions/list" as _list;

$list: (1, 2, 3, 1, 3, 4, 5);

_list.remove-duplicates($list); // (1, 2, 3, 4, 5)

reverse($list)

Reverses the order of the values within a list.

Parameters:

• $list: the list to reverse the order of the items.

@use "@littlemissrobot/sass-functions/list" as _list;

$list: (1, 2, 3, 4, 5);

_list.reverse($list); // (5, 4, 3, 2, 1)

sort-low-to-high($list)

Sorts a list of numbers from lowest to highest.

Parameters:

• $list: the list to sort.

@use "@littlemissrobot/sass-functions/list" as _list;

$list: (2, 1, 5, 3, 4);

_list.sort-low-to-high($list); // (1, 2, 3, 4, 5)

Map

These functions are namespace with map_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.map_includes($map, color);

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/map" as _map;

_map.includes($map, color);

collect($maps...)

The standard map-merge function only lets you merge 2 maps. This function makes use of the method, but merges as many maps together as you want.

Parameters:

• $maps: any amount of maps to merge together

@use "@littlemissrobot/sass-functions/map" as _map;

$map1: (
    display: flex;
    justify-content: center,
    align-items: center,
);

$map2: (
    font-size: 16px,
    line-height: 24px,
);

$map3: (
    color: white,
    background-color: black,
);

_map.sort-low-to-high($map1, $map2, $map3);
// result: (
//  display: flex;
//  justify-content: center,
//  align-items: center,
//  font-size: 16px,
//  line-height: 24px,
//  color: white,
//  background-color: black,
// );

get($map, $path)

Retrieve a value from a map which can contain mulitple more maps with values. Pass a path as a string, where each key is seperated by a space. Each key within that string represents the keys until you reach a certain value within the map.

Parameters:

• $map: The map to retrieve the value from
• $path: The path of keys to the value

@use "@littlemissrobot/sass-functions/map" as _map;

$colors: (
    brand: (
        primary: black,
        secondary: white
    ),
    typo: (
        title: (
            h1: black,
            h2: red,
            h3: blue
        ),
        text: (
            p: black,
            small: (
                base: gray,
                inverse: white,
            ),
        )
    )
);

_map.get($colors, "brand primary"); // black
_map.get($colors, "typo title h1"); // black
_map.get($colors, "typo text small base"); // gray

get-from-list($map, $list)

Generate a new map of items, based on the values within the list, which represent the keys in the map.

Parameters:

• $map: The map with the keys and values
• $list: The list to create a new map from

@use "@littlemissrobot/sass-functions/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

$list1: (viewport-7, viewport-9);
$list2: (viewport-3, viewport-9, viewport-12);

_map.get-from-list($breakpoints, $list1);
// result: (
//  viewport-7: 720px,
//  viewport-9: 992px,
// );

_map.get-from-list($breakpoints, $list2);
// result: (
//  viewport-3: 360px,
//  viewport-9: 992px,
//  viewport-12: 1200px,
// );

get-keys-from-list($map, $list)

Generate a new list of keys from a map, based on the items within a map and a list representing the values in that map.

Parameters:

• $map: The map with the keys and values
• $list: The list to create a new list from

@use "@littlemissrobot/sass-functions/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

$list1: (720px, 992px);
$list2: (360px, 992px, 1200px);

_map.get-keys-from-list($breakpoints, $list1);
// result: (viewport-7, viewport-9);

_map.get-keys-from-list($breakpoints, $list2);
// result: (viewport-3, viewport-9, viewport-12);

get-values-from-list($map, $list)

Generate a new list of values from a map, based on the items within a map and a list representing the keys in that map.

Parameters:

• $map: The map with the keys and values
• $list: The list to create a new list from

@use "@littlemissrobot/sass-functions/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

$list1: (viewport-7, viewport-9);
$list2: (viewport-3, viewport-9, viewport-12);

_map.get-values-from-list($breakpoints, $list1);
// result: (720px, 992px);

_map.get-values-from-list($breakpoints, $list2);
// result: (360px, 992px, 1200px);

includes($map, $key)

Checks if a map contains a certain key.

Parameters:

• $map: The map to search
• $key: The item to search for

@use "@littlemissrobot/sass-functions/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

_map.includes($breakpoints, viewport-7); // true
_map.includes($breakpoints, viewport-2); // false

is-low-to-high($map)

Checks if the numbers, as values, in the map are ordered lowest to highest.

Parameters:

• $map: the map which contains the keys with its number.

@use "@littlemissrobot/sass-functions/map" as _map;

$map1: (
    viewport-7: 720px,
    viewport-3: 360px,
    viewport-9: 960px
);

$map2: (
    viewport-3: 360px,
    viewport-7: 720px,
    viewport-9: 960px
);

_map.is-low-to-high($map1); // false
_map.is-low-to-high($map2); // true

reverse($map)

Reverses the order of the items within a map.

Parameters:

• $map: the map to reverse the order of the items.

@use "@littlemissrobot/sass-functions/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

_map.reverse($breakpoints);
// result: (
//  viewport-12: 1200px
//  viewport-9: 992px,
//  viewport-7: 720px,
//  viewport-4: 480px,
//  viewport-3: 360px,
// );

trim($map, $target)

Trims a map to a certain target key. Returns a new map that is trimmed down until the key is met.

Parameters:

• $map: the map to trim
• $target: the target key to trim the map to.

@use "@littlemissrobot/sass-functions/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

_map.trim($breakpoints, viewport-7);
// result: (
//   viewport-3: 360px,
//   viewport-4: 480px,
//   viewport-7: 720px
// );

Math

These functions are namespace with math_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.math_pow(8, 2);

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/math" as _math;

_math.pow(8, 2);

Decimal($value, $amount)

Round a number's value after the comma (decimals) to a certain amount.

Parameters:

• $value: The number and its decimals to round
• $target: The target amount to round the decimals to

@use "@littlemissrobot/sass-functions/math" as _math;

_math.decimal(1.12345, 2); // 1.12
_math.decimal(1.123456789, 5); // 1.12346

Pow($number, $exponent)

Power function / exponent operator which accepts positive, negative (integer, float) exponents.

Parameters:

• $number: The number to apply the exponent operator to
• $exponent: The exponent used ont he number

@use "@littlemissrobot/sass-functions/math" as _math;

_math.pow(2, 8); // 256
_math.pow(4, 2); // 16

Number

These functions are namespace with number_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.number_strip(16px);

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/number" as _number;

_number.strip(16px);

is-int($value)

Check if a number is of type integer (no decimals).

Parameters:

• $value: The value to check

@use "@littlemissrobot/sass-functions/number" as _number;

_number.is-int("sass-functions"); // false
_number.is-int(20); // true
_number.is-int(20.5); // false

randomize($min, $max)

Generate a random number between a minimum and maximum value.

Parameters:

• $min: The minimum number to randomize a number between
• $max: The maximum number to randomize a number between

@use "@littlemissrobot/sass-functions/number" as _number;

_number.randomize(0, 10); // 4
_number.is-int(0, 10); // 5
_number.is-int(2, 8); // 6
_number.is-int(2, 8); // 7

strip($value)

Removes the unit from a value.

Parameters:

• $value: The number to remove the unit from

@use "@littlemissrobot/sass-functions/number" as _number;

_number.strip(10px); // 10
_number.strip(7rem); // 7

valid($value)

Checks whether or not the passed value is a number. Very similar to is-int, but this value can have decimals.

Parameters:

• $value: The number to validate

@use "@littlemissrobot/sass-functions/number" as _number;

_number.valid(10px); // true
_number.valid(7rem); // true
_number.valid(2.5px); // true
_number.valid("sass-functions"); // false
_number.valid(center); // false

String

These functions are namespace with string_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.string_includes("Functions", "F");

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/string" as _string;

_string.includes("Functions", "F");

escape($value)

Escapes a value and adds extra slashes to special characters. This can be useful for creating a class with special characters.

Parameters:

• $value: The number to escape

@use "@littlemissrobot/sass-functions/string" as _string;

_string.escape(100%); // 100\%
_string.escape(l-grid__col:12/12); // l-grid__col\:12\/12

includes($string, $characters)

Check if string contains certain characters. Returns a boolean.

Parameters:

• $string: The string to search
• $characters: The characters to search for

@use "@littlemissrobot/sass-functions/string" as _string;

_string.escape(100%); // 100\%
_string.escape(l-grid__col:12/12); // l-grid__col\:12\/12

replace($string, $search, $replace)

Replace a certain part of a string by another string.

Parameters:

• $string: The string containing the characters to replace
• $search: The characters to search for
• $replace: The characters to replace the searched with

@use "@littlemissrobot/sass-functions/string" as _string;

_string.replace("sass-functions", "sass", "dart-sass"); // dart-sass-functions

split($string, $separator)

Create a list from a string by defining a character to split the string at.

Parameters:

• $string: The string to split
• $separator: The character to split the string at

@use "@littlemissrobot/sass-functions/string" as _string;

_string.split("sass-functions", "-"); // (sass, functions)

to($string, $separator)

Converts a value to a string

Parameters:

• $value: The value to convert to

@use "@littlemissrobot/sass-functions/string" as _string;

_string.to(10px); // "10px"

Px

These functions are namespace with px_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.px_rem(16px);

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/px" as _px;

_px.rem(16px);

em($value, $base)

Converts a pixel value to em.

Parameters:

• $value: The value to convert
• $base (optional): The base font-size on the body, by default is 16.

@use "@littlemissrobot/sass-functions/string" as _px;

_px.em(16px); // 1em
_px.em(10px, 16px); // 0.625em
_px.em(32px); // 2em
_px.em(20px, 10px); // 2em

rem($value, $base)

Converts a pixel value to rem.

Parameters:

• $value: The value to convert
• $base (optional): The base font-size on the body, by default is 16.

@use "@littlemissrobot/sass-functions/string" as _px;

_px.rem(16px); // 1rem
_px.rem(10px, 16px); // 0.625rem
_px.rem(32px); // 2rem
_px.rem(20px, 10px); // 2rem

Rem

These functions are namespace with rem_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.rem_px(1rem);

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/rem" as _rem;

_rem.px(1rem);

px($value, $base)

Converts a rem value to px.

Parameters:

• $value: The value to convert
• $base (optional): The base font-size on the body, by default is 16.

@use "@littlemissrobot/sass-functions/string" as _rem;

_rem.px(1rem); // 16px
_rem.px(2rem); // 32px
_rem.px(1rem, 10px); // 10px
_rem.px(2rem, 10px); // 20px